// package toml 提供 TOML 格式的序列化与反序列化功能
// 基于 github.com/BurntSushi/toml 库实现，支持将任意类型值与 TOML 格式数据相互转换
package toml

import "github.com/BurntSushi/toml" // 依赖第三方 TOML 处理库，提供核心编解码能力

// Name 编解码器标识名称，固定为 "toml"
const Name = "toml"

// DefaultCodec 是默认的 TOML 编解码器实例，提供便捷的编解码入口
var DefaultCodec = &codec{}

// codec 实现 TOML 编解码功能的结构体
// 无内部状态，线程安全，通过封装第三方库方法实现编解码逻辑
type codec struct{}

// Name 返回编解码器的标识名称
func (codec) Name() string {
	return Name
}

// Marshal 将任意类型值序列化为 TOML 格式的字节切片（编码）
// 参数：
//
//	v - 待序列化的任意类型值（支持结构体、map、基础类型等，需符合 TOML 语法规范）
//
// 返回值：
//
//	[]byte - 序列化后的 TOML 文本字节切片
//	error - 序列化过程中发生的错误（如类型不支持、数据结构不符合 TOML 规范等）
func (codec) Marshal(v interface{}) ([]byte, error) {
	return toml.Marshal(v)
}

// Unmarshal 将 TOML 格式的字节切片反序列化为目标类型（解码）
// 参数：
//
//	data - 待反序列化的 TOML 文本字节切片
//	v - 接收反序列化结果的指针（需为结构体、map 等可赋值类型的指针，否则无法写入结果）
//
// 返回值：
//
//	error - 反序列化过程中发生的错误（如数据格式错误、类型不匹配、v 非指针等）
func (codec) Unmarshal(data []byte, v interface{}) error {
	return toml.Unmarshal(data, v)
}

// Marshal 包级 TOML 序列化函数，基于 DefaultCodec 实现
// 功能与 codec.Marshal 一致，提供更简洁的调用方式
func Marshal(v interface{}) ([]byte, error) {
	return DefaultCodec.Marshal(v)
}

// Unmarshal 包级 TOML 反序列化函数，基于 DefaultCodec 实现
// 功能与 codec.Unmarshal 一致，提供更简洁的调用方式
func Unmarshal(data []byte, v interface{}) error {
	return DefaultCodec.Unmarshal(data, v)
}
